Custom stylesheets

It’s easy to customize rendering of PDF, HTML and plain text because Novelang relies on FO (Formatting Objects) stylesheets.

Novelang looks for stylesheets in that order:

In the directories set by --style-dirs option at startup.
Or in a style directory right under the project directory (from where Novelang was launched), if the --style-dirs option was not set.
Finally, inside Novelang’s jars files under the /style directory.

By default Novelang attempts to render final document using the stylesheet with the name of corresponding format. Otherwise, it uses a default, built-in stylesheet.

MIME type extension                .pdf     .html
Corresponding default stylesheet    pdf.xsl  html.xsl

After launching Novelang HTTP daemon, you can use the stylesheet query parameter to override any other stylesheet name:

http://localhost:8080/chapter-1.html?stylesheet=html-beautiful.xsl

Stylesheets may be defined for a whole Opus as explained later, see the “mapstylesheet” command.

eXtensible Stylesheet Language

The stylesheets are written in XSL/FO, which stands for eXtensible Stylesheet Language/Formatting Objects. Both are standards developed by the W3C (World Wide Web Consortium). The reference documentation is here.

FO may look complex, because typesetting is inherently complex, and because of the lack of synthetic documentation. So you may be interested by this document explaining importants FO basics.

You’ll find valuable tutorials on ZVon, Webucator and Dave Pawson’s site.

XSL reuse

Novelang supports stylesheet reuse with standard xsl:import command. You can reuse Novelang’s bundled stylesheets:

general-punctuation.xsl
punctuation-FR.xsl
punctuation-US-EN.xsl
default-pdf.xsl
default-html.xsl

Character entities

Novelang stylesheets support inclusion of character entities. This means, you can include definition of characters which can no be typed verbatim in the stylesheet, like the non-breaking space.

Such a definition looks like this:

<!ENTITY nbsp   "&#160;" >

So inside the stylesheet you just have to type “ ” instead of “ ”.

Novelang comes bundled with those files. Here is how to refer them (it’s quite verbose as XML always is):

<!DOCTYPE doctype [

  <!ENTITY % ISOnum PUBLIC
      "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
      "ISOnum.pen"
  >
  %ISOnum;

  <!ENTITY % ISOpub PUBLIC
      "ISO 8879:1986//ENTITIES Publishing//EN//XML"
      "ISOpub.pen"
  >
  %ISOpub;

  <!ENTITY % ISOlat1 PUBLIC
      "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
      "ISOlat1.pen"
  >
  %ISOlat1;

]>

For HTML documents, those entities are automatically HTML-escaped when their system name starts with ISO 8879:1986//ENTITIES as above.

Other functions

Java developers can add functions on their own in order to augment standard set of functions available from an XSL stylesheet. By now there is one, numberAsText which transforms a number into its textual equivalent. For example, number “43” will become “forty-three”.

In addition to standard namespace declarations, the stylesheet must contain the xalan and nlx namespaces like below:

<xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    xmlns:n="http://novelang.org/book-xml/1.0"
    xmlns:xalan="http://xml.apache.org/xalan"
    xmlns:nlx="xalan://org.novelang.rendering.xslt.Numbering"
>

Here is how to call the numberAsText function:

<xsl:value-of select="nlx:numberAsText(43,'EN','capital')" />

The first parameter is the number itself (could be a standard XSL function like position() as well). Currently the number must be included in the 0-50 range.

The second parameter is the locale. Currently only EN and FR.

The third parameter is the case. Currently lower, upper and capital are supported.

Look at the complete example in samples/numbering/numbering.xsl in the Novelang distribution.

version 0.56.0